home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / shmalloc.z / shmalloc
Encoding:
Text File  |  2002-10-03  |  9.9 KB  |  117 lines
  1.  
  2. SHMALLOC(3C)                                                   SHMALLOC(3C)
  3.  
  4.  
  5. NNNNAAAAMMMMEEEE
  6.      sssshhhhmmmmaaaalllllllloooocccc, sssshhhhffffrrrreeeeeeee, sssshhhhmmmmeeeemmmmaaaalllliiiiggggnnnn, sssshhhhrrrreeeeaaaalllllllloooocccc, sssshhhhmmmmaaaalllllllloooocccc____cccchhhheeeecccckkkk,
  7.      sssshhhhmmmmaaaalllllllloooocccc____ssssttttaaaattttssss - Symmetric heap memory management functions
  8.  
  9. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  10.      ####iiiinnnncccclllluuuuddddeeee <<<<mmmmpppppppp////sssshhhhmmmmeeeemmmm....hhhh>>>>
  11.  
  12.      vvvvooooiiiidddd ****sssshhhhmmmmaaaalllllllloooocccc((((ssssiiiizzzzeeee____tttt _s_i_z_e))));;;;
  13.  
  14.      vvvvooooiiiidddd sssshhhhffffrrrreeeeeeee((((vvvvooooiiiidddd ****_p_t_r))));;;;
  15.  
  16.      vvvvooooiiiidddd ****sssshhhhrrrreeeeaaaalllllllloooocccc((((vvvvooooiiiidddd ****_p_t_r,,,, ssssiiiizzzzeeee____tttt _s_i_z_e))));;;;
  17.  
  18.      vvvvooooiiiidddd ****sssshhhhmmmmeeeemmmmaaaalllliiiiggggnnnn((((ssssiiiizzzzeeee____tttt _a_l_i_g_n_m_e_n_t,,,, ssssiiiizzzzeeee____tttt _s_i_z_e))));;;;
  19.  
  20.      iiiinnnntttt sssshhhhmmmmaaaalllllllloooocccc____cccchhhheeeecccckkkk((((iiiinnnntttt _l_e_v_e_l))));;;;
  21.  
  22.      vvvvooooiiiidddd sssshhhhmmmmaaaalllllllloooocccc____ssssttttaaaattttssss((((iiiinnnntttt _l_e_v_e_l))));;;;
  23.  
  24.      eeeexxxxtttteeeerrrrnnnn lllloooonnnngggg mmmmaaaalllllllloooocccc____eeeerrrrrrrroooorrrr;;;;
  25.  
  26. SSSSTTTTAAAANNNNDDDDAAAARRRRDDDDSSSS
  27.      SGI extension
  28.  
  29. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  30.      The sssshhhhmmmmaaaalllllllloooocccc function returns a pointer to a block of at least _s_i_z_e
  31.      bytes suitably aligned for any use.  This space is allocated from the
  32.      symmetric heap (in contrast to mmmmaaaalllllllloooocccc(3C), which allocates from the
  33.      private heap).
  34.  
  35.      The sssshhhhmmmmeeeemmmmaaaalllliiiiggggnnnn function allocates a block in the symmetric heap that
  36.      has a byte alignment specified by the _a_l_i_g_n_m_e_n_t argument.
  37.  
  38.      The sssshhhhffffrrrreeeeeeee function causes the block to which _p_t_r points to be
  39.      deallocated, that is, made available for further allocation.  If _p_t_r
  40.      is a null pointer, no action occurs; otherwise, if the argument does
  41.      not match a pointer earlier returned by a symmetric heap function, or
  42.      if the space has already been deallocated, mmmmaaaalllllllloooocccc____eeeerrrrrrrroooorrrr is set to
  43.      indicate the error, and sssshhhhffffrrrreeeeeeee returns.
  44.  
  45.      The sssshhhhrrrreeeeaaaalllllllloooocccc function changes the size of the block to which _p_t_r
  46.      points to the size (in bytes) specified by _s_i_z_e.  The contents of the
  47.      block are unchanged up to the lesser of the new and old sizes.  If the
  48.      new size is larger, the value of the newly allocated portion of the
  49.      block is indeterminate.  If _p_t_r is a null pointer, the sssshhhhrrrreeeeaaaalllllllloooocccc
  50.      function behaves like the sssshhhhmmmmaaaalllllllloooocccc function for the specified size.
  51.      If _s_i_z_e is 0 and _p_t_r is not a null pointer, the block to which it
  52.      points is freed.  Otherwise, if _p_t_r does not match a pointer earlier
  53.      returned by a symmetric heap function, or if the space has already
  54.      been deallocated, the mmmmaaaalllllllloooocccc____eeeerrrrrrrroooorrrr variable is set to indicate the
  55.      error, and sssshhhhrrrreeeeaaaalllllllloooocccc returns a null pointer.  If the space cannot be
  56.      allocated, the block to which _p_t_r points is unchanged.
  57.  
  58.      The sssshhhhmmmmaaaalllllllloooocccc, sssshhhhffffrrrreeeeeeee, and sssshhhhrrrreeeeaaaalllllllloooocccc functions are provided so that
  59.      multiple PEs in an application can allocate symmetric, remotely
  60.      accessible memory blocks.  these memory blocks can then be used with
  61.      the symmetric memory (sssshhhhmmmmeeeemmmm) library.  Each of these functions call
  62.      the sssshhhhmmmmeeeemmmm____bbbbaaaarrrrrrrriiiieeeerrrr____aaaallllllll(3) function before returning; this ensures that
  63.      all PEs participate in the memory allocation, and that the memory on
  64.      other PEs can be used as soon as the local PE returns.  The user is
  65.      responsible for calling these functions with identical argument(s) on
  66.      all PEs; if differing _s_i_z_e arguments are used, subsequent calls may
  67.      not return the same symmetric heap address on all PEs.
  68.  
  69.      The sssshhhhmmmmaaaalllllllloooocccc____cccchhhheeeecccckkkk function checks the consistency of sssshhhhmmmmaaaalllllllloooocccc's
  70.      memory structure.  If _l_e_v_e_l is less than 0, sssshhhhmmmmaaaalllllllloooocccc____cccchhhheeeecccckkkk silently
  71.      performs validation of the symmetric heap, and returns 0 if the heap
  72.      is consistent, or nonzero if the heap has been corrupted.  If _l_e_v_e_l
  73.      equals 0, sssshhhhmmmmaaaalllllllloooocccc____cccchhhheeeecccckkkk prints a message to ssssttttddddeeeerrrrrrrr that describes the
  74.      first inconsistency found.  If _l_e_v_e_l is greater than  0,
  75.      sssshhhhmmmmaaaalllllllloooocccc____cccchhhheeeecccckkkk prints a line to ssssttttddddeeeerrrrrrrr that describes each symmetric
  76.      heap block in addition to checking the symmetric heap.
  77.  
  78.      The sssshhhhmmmmaaaalllllllloooocccc____ssssttttaaaattttssss function prints out memory manager statistics and
  79.      heap block information to ssssttttddddoooouuuutttt.  If _l_e_v_e_l equals 0, sssshhhhmmmmaaaalllllllloooocccc____ssssttttaaaattttssss
  80.      reports the number of calls to each symmetric heap function, as well
  81.      as summary statistics on the number and total size of the busy blocks,
  82.      free blocks, and "spec" blocks (that is, blocks that are created by
  83.      user calls to sssshhhhssssbbbbrrrreeeeaaaakkkk) in the symmetric heap.  If _l_e_v_e_l equals 1,
  84.      sssshhhhmmmmaaaalllllllloooocccc____ssssttttaaaattttssss prints a line with a **** for each busy block, a .... for
  85.      each free block, and a @@@@ for each "spec" block, in addition to the
  86.      level 0 statistics.  If _l_e_v_e_l equals 2, sssshhhhmmmmaaaalllllllloooocccc____ssssttttaaaattttssss prints a line
  87.      that describes each symmetric heap block, in addition to the level 0
  88.      statistics.  The number of calls for each function are available only
  89.      by linking with the lllliiiibbbbmmmmaaaalllllllloooocccc library; all of the other information is
  90.      available in the default memory manager.
  91.  
  92. CCCCAAAAUUUUTTTTIIIIOOOONNNNSSSS
  93.      The sssshhhhmmmmaaaalllllllloooocccc, sssshhhhffffrrrreeeeeeee, and sssshhhhrrrreeeeaaaalllllllloooocccc functions differ from the private
  94.      heap allocation functions in that all PEs in an application must call
  95.      them (a barrier is used to ensure this).  The sssshhhhmmmmaaaalllllllloooocccc____cccchhhheeeecccckkkk, and
  96.      sssshhhhmmmmaaaalllllllloooocccc____ssssttttaaaattttssss functions do not use a barrier, and can be used by a
  97.      subset of all PEs.
  98.  
  99. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEESSSS
  100.      The sssshhhhmmmmaaaalllllllloooocccc function returns a pointer to the allocated space (which
  101.      should be identical on all PEs); otherwise, it returns a null pointer
  102.      (with mmmmaaaalllllllloooocccc____eeeerrrrrrrroooorrrr set).
  103.  
  104.      The sssshhhhffffrrrreeeeeeee and sssshhhhmmmmaaaalllllllloooocccc____ssssttttaaaattttssss functions return no value.
  105.  
  106.      The sssshhhhrrrreeeeaaaalllllllloooocccc function returns a pointer to the allocated space (which
  107.      may have moved); otherwise, it returns a null pointer (with
  108.      mmmmaaaalllllllloooocccc____eeeerrrrrrrroooorrrr set).
  109.  
  110.      If the symmetric heap has been corrupted, the sssshhhhmmmmaaaalllllllloooocccc____cccchhhheeeecccckkkk function
  111.      returns nonzero; otherwise, it returns 0.
  112.  
  113. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  114.      iiiinnnnttttrrrroooo____sssshhhhmmmmeeeemmmm(3), mmmmaaaalllllllloooocccc(3C), mmmmaaaalllllllloooocccc....hhhh(3C)
  115.  
  116.      bbbbrrrrkkkk(2)
  117.